Note: This is draft documentation for 8.5.2, and is subject to change in the
final release.
Deploying an XPage Library on a 8.5.2 Domino Server
In Lotus Domino Server 8.5.2 there is a new deployment method as we have moved to having OSGI framework on the server. OSGI is a Java based framework for running code in bundles or plugins. It now handles the loading of the XPages runtime and by default means it also handles the loading of XPage libraries. In previous releases users will be familiar with deploying their third party libraries to c:\Domino\xsp\shared\lib. For 8.5.2 your third party libraries will continue to work if they are located in \xsp\shared\lib but we recommend that you think about moving them to the new directories as plugins and features if possible.
To deploy an XPage library, you need to take the built versions of your feature and plugin and place them in the osgi\shared\eclipse\features and osgi\shared\eclipse\plugins directories respectively. Here is a link to the previous article on building your XPage library. Creating an XPage Library
Restart your server and your library has been installed and is ready to use.
Common Problems
Accidentally putting your library in Notes osgi folder instead of the Domino server osgi folder. There is an osgi folder on the notes client also which is used for the web preview if the application is local . It can sometimes be confusing if your moving around environments so be careful not to place your library there instead of the Domino osgi directory.
Deploying an XPages Library in a 8.5.2 Notes Client
We are leveraging the Widgets technology that was introduced in Lotus Domino 8.5.1 which allows administrators to install widgets on their clients via policies or eclipse preferences pushed down from the Domino Server or alternatively allows users to install libraries from their MyWidgets sidebar as they need if they have the appropriate privileges.
Creating the Widget Catalog
As an administrator you would create a new Widget Catalog like below on a Domino Server. A widget catalog is a server based application that centrally manages all your widgets or in our case, it is going to manage our XPage Library.
Creating a Widget in the Widget Catalog
Click on the "Add Widget to Catalog" to create a new widget. Give your widget a title and also create a category. This is important later in the process when you want to choose what library or libraries you want to install in your client. So you need to decide if you want to group libraries in one category together or if you are going to have one category per library, it's entirely up to you. For this simple use case we just have one library so will we use a category called "XPage Sample Library". Next you can choose which platforms you want your widget to run on, there are a number of options from Expeditor to Notes if you wish to restrict the widget to certain platforms. Next check the "Plugins and Features" option as this is our preferred widget type for an XPage Library.
Next you need to attach an XML definition that describes your widget and tells the client what to do with the widget when it is provisioned to the user .Here is a sample extension.xml file that is used to deploy this Sample XPage Library
What to take note of here is the URL property, this tells the widget where it can find the actual features and plugins it needs to install. These are placed in an eclipse update site nsf which is used as a host Notes application for the features and plugins.
Other properties that are of interest.
hideThumbnail="true" -Flag to tell widget to hide the widget in My Widgets sidebar pane. It will only be shown if the user chooses "Show All" in the MyWidgets sidebar
match="perfect" -Guarantees that provision engine will attempt to install the exact version that you have specified
shared="true" -Provided that shared="true" is set in the install manifest snippet ,as below, the plug-in is installed to
Notes_install_dir\framework\shared\eclipse. If there is no write access to that directory, the plug-in is installed to
Notes_install_dir\data\workspace\applications.
Create Updatesite nsf that contains the plugins and features
After completing the steps in the previous article
to create the plugin and feature for your library. There is an Eclipse Update Site template that can be used to host the plugins and features. It then can be used to import the plugins so that they can be provisioned to client machines using the widget definition.
After creating the updateSite, you just need to point it at the site.xml of your library update site that we created earlier. It will import the plugins and features into the nsf.
There is a handy option in the menu for showing the URL's which will need for your widget definition to define the url attribute. This gives you two URL's, either a NRPC or a HTTP url. Copy one of these across to your widget definition.
Enabling the Widgets in your Notes Client Manually
If your administrator has given you the details of the widget catalog server to connect to,then the quick way to enable Widgets, is to go to File->Preferences->Widget and fill in the fields. You can then select the categories you wish to install so if your administrator has told where where your XPage Library is, you simply check the category and it will begin to download the widgets contained in that category.
Alternatively an administrator might just send you an XML definition by email which you can drag across to the MyWidgets sidebar
Enabling the widget Catalog using a Policy
If you are an administrator then you can create a desktop policy which enforces what widget catalog server a client must use and also what categories to install on the clients machine. You can also set a number of other widget catalog specific preferences which are described here
http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.help.domino.admin.doc/DOC/H_ENABLING_TOOLBOX_FOR_USERS_OVER_MIDTOPIC_22549596829893143.html
What is important to remember here is the category that you defined for your XPage library earlier. One of the preferences is to tell the client what categories you want to install so as I was saying earlier it is important to have your XPage libraries categorised correctly.
After creating your policy, you need to assign that policy to the user's either by making it an organizational policy which is applied when a new user is registered or an explicit policy which you can apply to a user. When a user next logs in, the new desktop policy is applied.
Installing the Widget
Whether you are installing the library manually or it has been pushed down by an administrator, what you should see when the library is being installed is the following dialog asking do you want to install the feature and plugins.
You choose to install this plug-in and it prompts you to restart your notes client for the updates to take effect.
Next open the NSF application that depends on the library that you have installed and see that it works as it should.
Resources
More information on the Widget Catalog and the other topics discussed in this article can be found here:
http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.help.domino.admin.doc/DOC/H_CREATING_A_TOOLBOX_CATALOG_OVER.html